home *** CD-ROM | disk | FTP | other *** search
/ Aminet 30 / Aminet 30 (1999)(Schatztruhe)[!][Apr 1999].iso / Aminet / hard / hack / i2clib40.lha / i2clib40 / Developer / i2c.doc < prev    next >
Text File  |  1998-09-04  |  9KB  |  277 lines
  1. TABLE OF CONTENTS
  2.  
  3. i2c.library/SetI2CDelay
  4. i2c.library/SendI2C
  5. i2c.library/ReceiveI2C
  6. i2c.library/I2CErrText
  7. i2c.library/GetI2COpponent
  8. i2c.library/ShutDownI2C
  9. i2c.library/BringBackI2C
  10.  
  11. This file describes the recommended use of i2c.library V39+ only.
  12. Some functions have been added since V38, but more important, some functions
  13. have become obsolete and are not recommended anymore. So, for your own
  14. convenience, follow these guidelines and make your programs insist on V39.
  15.  
  16. i2c.library/SetI2CDelay                               i2c.library/SetI2CDelay
  17.  
  18.    NAME
  19.         SetI2CDelay -- Set the delay for I²C-bus clock-rate
  20.  
  21.    SYNOPSIS
  22.         oldval = SetI2CDelay(ticks);
  23.           D0                  D0
  24.  
  25.         ULONG SetI2CDelay(ULONG);
  26.  
  27.    FUNCTION
  28.         Set the delay for the I²C-bus clock, which must not exceed a
  29.         frequency of 100 KHz (or maybe less, with unfavourable hardware
  30.         configurations).
  31.  
  32.    INPUTS
  33.         ticks - Number of idle reads from a CIA register, which will be
  34.                 added to every HI and LO SCL pulse.  This is a slow
  35.                 operation (about 1.5 µs with OCS/ECS, slightly less with
  36.                 AA chipset), regardless of CPU speed. Small values (0, 1,
  37.                 2, 3, ...) will normally do.
  38.                 A magic value I2CDELAY_READONLY will not change anything,
  39.                 should you only want to read the old delay.
  40.  
  41.    RESULTS
  42.         oldval - The old delay value, just in case you are curious.  You
  43.                 don't have to restore it, you need not even look at it.
  44.  
  45.    NOTES
  46.         Starting with i2c.library V40, the default delay value may be set
  47.         globally by an environment variable (I2CDELAY).  So for most programs
  48.         it's now reasonably safe to assume that the delay value has already
  49.         been set correctly, and they need not call SetI2CDelay at all.
  50.         Otherwise remember that the delay value affects all clients of the
  51.         library in the same way, not only the calling program.  And if you
  52.         do change it, never set it to a hardcoded value, but one that is
  53.         somehow adjustable by the end user.
  54.  
  55.    SEE ALSO
  56.  
  57.    BUGS
  58.  
  59. i2c.library/SendI2C                                       i2c.library/SendI2C
  60.  
  61.    NAME
  62.         SendI2C -- Transmit bytes on the I²C-bus
  63.  
  64.    SYNOPSIS
  65.         error = SendI2C(addr, number, data);
  66.           D0             D0    D1      A1
  67.  
  68.         ULONG SendI2C(UBYTE, UWORD, UBYTE []);
  69.  
  70.    FUNCTION
  71.         Send data to a device connected to the I²C-bus hardware.
  72.  
  73.    INPUTS
  74.         addr - Address of device to receive the transmitted data.
  75.         number - Number of bytes to transmit from the array specified
  76.                 by data.
  77.         data - Array, where the data to be transmitted is placed in.
  78.  
  79.    RESULTS
  80.         error - may be considered as three UBYTE's: 0x00AABBCC, with
  81.                 CC: Zero, if an error occurred.
  82.                 BB: I/O error number (see i2c_library.h)
  83.                 AA: Allocation error number (see i2c_library.h)
  84.  
  85.    NOTES
  86.         The LSB in the addr byte will always be cleared to make a valid
  87.         I²C-bus write address.  You can take advantage of this and address
  88.         a chip for both read and write using the same symbolic constant.
  89.  
  90.    SEE ALSO
  91.         ReceiveI2C
  92.         I2CErrText
  93.  
  94.    BUGS
  95.  
  96. i2c.library/ReceiveI2C                                 i2c.library/ReceiveI2C
  97.  
  98.    NAME
  99.         ReceiveI2C -- Receive bytes from the I²C-bus
  100.  
  101.    SYNOPSIS
  102.         error = ReceiveI2C(addr, number, data);
  103.           D0                D0    D1      A1
  104.  
  105.         ULONG ReceiveI2C(UBYTE, UWORD, UBYTE []);
  106.  
  107.    FUNCTION
  108.         Receive data from a device connected to the I²C-bus hardware.
  109.  
  110.    INPUTS
  111.         addr - Address of device to receive data from.
  112.         number - Number of bytes to receive from the specified device.
  113.         data - Array, where to put the received data.
  114.  
  115.    RESULTS
  116.         error - may be considered as three UBYTE's: 0x00AABBCC, with
  117.                 CC: Zero, if an error occurred.
  118.                 BB: I/O error number (see i2c_library.h)
  119.                 AA: Allocation error number (see i2c_library.h)
  120.  
  121.    NOTES
  122.         Be sure that the size of the data-array is the same or larger than
  123.         the requested number of bytes to receive.
  124.         The LSB in the addr byte will always be set to make a valid I²C-bus
  125.         read address.
  126.  
  127.    SEE ALSO
  128.         SendI2C
  129.         I2CErrText
  130.  
  131.    BUGS
  132.  
  133. i2c.library/I2CErrText                                 i2c.library/I2CErrText
  134.  
  135.    NAME
  136.         I2CErrText -- give a plaintext translation of an error code
  137.  
  138.    SYNOPSIS
  139.         errtext = I2CErrText(errnum);
  140.           D0                   D0
  141.  
  142.         STRPTR I2CErrText(ULONG);
  143.  
  144.    FUNCTION
  145.         Gives a plaintext translation of an I²C-bus I/O error, nice
  146.         information for the user.
  147.  
  148.    INPUTS
  149.         errnum - the error code as reported by SendI2C or ReceiveI2C
  150.  
  151.    RESULTS
  152.         errtext - STRPTR to a brief description (up to 20 chars) of the
  153.                 supplied error code.
  154.  
  155.    NOTES
  156.         Supplying random (i. e. illegal) error codes is safe and will only
  157.         return a "???" string.
  158.         If you want to report only error codes that are really errors, not
  159.         "OK", look at their low-order byte: it's zero with "real errors".
  160.  
  161.    SEE ALSO
  162.         SendI2C
  163.         ReceiveI2C
  164.  
  165.    BUGS
  166.  
  167. i2c.library/GetI2COpponent                         i2c.library/GetI2COpponent
  168.  
  169.    NAME
  170.         GetI2COpponent -- Get name of task using our hardware
  171.  
  172.    SYNOPSIS
  173.         name = GetI2COpponent();
  174.          D0
  175.  
  176.         STRPTR GetI2COpponent(void);
  177.  
  178.    FUNCTION
  179.         When hardware allocation via misc.resource fails, a STRPTR
  180.         description of the current resource owner is returned.  i2c.library
  181.         stores this name and lets you look at it with this function.
  182.  
  183.    RESULTS
  184.         name - STRPTR to someone using the hardware that is needed
  185.                 for the I²C-bus interface (e.g. "serial.device"), or
  186.                 NULL, if there is no name to return.
  187.  
  188.    NOTES
  189.         This function is best used to provide additional user information
  190.         in situations where an error code returned by SendI2C/ReceiveI2C
  191.         indicates a resource conflict. (Check for ((err >> 8) & 0xff) ==
  192.         I2C_HARDW_BUSY.)
  193.         Note that even then, you might still receive a NULL pointer!  Check
  194.         for this before you try to process the string!
  195.  
  196.    SEE ALSO
  197.  
  198.    BUGS
  199.  
  200. i2c.library/ShutDownI2C                               i2c.library/ShutDownI2C
  201.  
  202.    NAME
  203.         ShutDownI2C -- Release all allocated hardware immediately
  204.  
  205.    SYNOPSIS
  206.         ShutDownI2C();
  207.  
  208.         void ShutDownI2C(void);
  209.  
  210.    FUNCTION
  211.         Returns the allocated hardware to the system, no matter how many
  212.         clients have the library open, and all subsequent I/O calls will
  213.         fail.  Not even AllocI2C (called implicitly when a new client opens
  214.         the library) will work, only BringBackI2C will return things to
  215.         normal.
  216.  
  217.    INPUTS
  218.  
  219.    RESULTS
  220.  
  221.    NOTES
  222.         You should only call this function in direct response to a user
  223.         command.  Using it silently might cause major confusion.
  224.         DON'T misunderstand this function as a cleanup routine.  All you
  225.         have to do is close the library before you quit, and if you
  226.         were the last client, the allocated hardware will be returned
  227.         automatically.
  228.         DON'T call this function "just to be nice".  If your program
  229.         typically runs for a long time but only needs the I²C-bus every now
  230.         and then, system-friendly behaviour would be:  Open the library
  231.         every time you need it, call the functions you need, and then close
  232.         it again.
  233.         Note that there are now many different implementations of
  234.         i2c.library, using a wide variety of hardware resources, so you
  235.         don't know what resources this call will return.  It might even
  236.         affect resources that aren't really needed elsewhere in the system
  237.         (zorro board or floppy disk unit for example).
  238.  
  239.    SEE ALSO
  240.         BringBackI2C
  241.  
  242.    BUGS
  243.  
  244. i2c.library/BringBackI2C                             i2c.library/BringBackI2C
  245.  
  246.    NAME
  247.         BringBackI2C -- Undo the effect of ShutDownI2C
  248.  
  249.    SYNOPSIS
  250.         err = BringBackI2C();
  251.          D0
  252.  
  253.         BYTE BringBackI2C(void);
  254.  
  255.    FUNCTION
  256.         Removes the lock set up by ShutDownI2C and then tries to allocate
  257.         the needed hardware again.
  258.  
  259.    INPUTS
  260.  
  261.    RESULTS
  262.         err - an error, if hardware allocation failed, zero if OK.
  263.                 You need not look at this return value, because even if
  264.                 BringBackI2C "fails", you don't have to call it again.
  265.                 The lock will have been removed in any case, and that's
  266.                 all that matters.
  267.  
  268.    NOTES
  269.         You can translate the return value to plaintext using I2CErrText,
  270.         but you have to shift it first: call I2CErrText(err<<16).
  271.  
  272.    SEE ALSO
  273.         ShutDownI2C
  274.  
  275.    BUGS
  276.  
  277.